• chore(engine): publish engine bases in ci #4649 : 3 dependent PRs (#4650 , #4652 , #4666 )
• chore: lockfile lefthook #4647
• fix(rivetkit): surface native sqlite kv errors to callers #4645
• fix(rivetkit): prevent sleep races during disconnect and db work #4644
• fix(rivetkit): isolate engine envoys and propagate startup failures #4643
• test(rivetkit): remove wasm sqlite-only fixtures and coverage #4642
• chore(sqlite-vfs): remove wasm sqlite packages and workspace wiring #4641
• chore(rivetkit): remove wasm sqlite runtime #4614
• fix(sqlite-native): restore native startup kv preload #4639
• fix(sqlite-native): delete metadata before chunk range #4638
• fix(sqlite-native): keep truncate cache coherent #4637
• fix(sqlite-vfs): use delete range for truncate cleanup #4636
• fix(sqlite-native): restore kv error hook #4635
• perf(sqlite-native): avoid cloning cached read chunks #4634
• perf(sqlite-native): gate kv operation labels #4633
• perf(sqlite-native): reuse read cache for partial writes #4632
• perf(sqlite-native): remove delete file existence probe #4631
• fix(sqlite-native): gate native read cache behind env var #4630 👈 (View in Graphite)
• fix(pegboard): isolate runner config dc lookup failures #4625 : 1 other dependent PR (#4626 )
• docs(pegboard): note runner config upsert split write risk #4624
• fix(pegboard): unpack global runner config keys correctly #4623
• fix(pegboard-gateway): enforce tunnel message state #4622
• fix(pegboard-runner): clear terminal tunnel routes #4621
• fix(pegboard): skip protocol version keys in runner pool backfill #4620
• fix(pegboard): create missing normal runner configs #4619
• fix(epoxy): reuse cached optimistic value #4618
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

PR #4630 Review: fix(sqlite-native) — Gate native read cache behind env var

Overview

This PR makes the native SQLite VFS read cache opt-in via the RIVETKIT_SQLITE_NATIVE_READ_CACHE env var (disabled by default) to match WASM VFS behavior. The change converts KvFileState.read_cache from HashMap<Vec<u8>, Vec<u8>> to Option<HashMap<Vec<u8>, Vec<u8>>> and guards all cache accesses with if let Some(read_cache) checks.

Correctness

Looks correct overall. All cache paths (read, write-through, truncate-invalidation, batch-flush) are consistently guarded.

One minor inefficiency in kv_io_file_control (the batch-flush path):

// Current code — allocates a Vec even when cache is disabled, then immediately drops it
let flushed: Vec<_> = std::mem::take(&mut state.dirty_buffer).into_iter().collect();
if let Some(read_cache) = state.read_cache.as_mut() {
    for (chunk_index, data) in flushed { ... }
}

When read_cache is None, the std::mem::take + into_iter().collect() allocates a Vec that is immediately dropped. The dirty_buffer is a BTreeMap, so std::mem::take already gives an owned, iterable value — the intermediate Vec is unnecessary. A tighter version:

let flushed = std::mem::take(&mut state.dirty_buffer);
if let Some(read_cache) = state.read_cache.as_mut() {
    for (chunk_index, data) in flushed {
        let key = kv::get_chunk_key(file.file_tag, chunk_index);
        read_cache.insert(key.to_vec(), data);
    }
}

This avoids the allocation when the cache is disabled and removes the redundant collect.

Design

• OnceLock for the env var is the right pattern — reads once at first call and caches the result for the lifetime of the process. Correct behavior.
• Storing read_cache_enabled in VfsContext means the setting is fixed at KvVfs::new() time and propagated to each KvFileState. This is intentional and correct; changing the env var after initialization has no effect, which is the expected behavior for a startup flag.
• Env var parsing ("1" | "true" | "yes" | "on") is user-friendly. No issues there.

Documentation

The new RIVETKIT_SQLITE_NATIVE_READ_CACHE env var is not documented anywhere. Per CLAUDE.md, config/behavior changes should be reflected in docs. Worth adding a note to website/src/content/docs/self-hosting/configuration.mdx or a dedicated SQLite/native VFS page so operators know this knob exists.

Code Style

• Comments added to truncate and batch-flush paths are clear and follow the project's sentence-style convention. Good.
• No formatting issues observed.

Summary

The core change is solid. The Vec allocation nit and missing docs are the only things worth addressing before merge.